+2001-12-03 Matthias Clasen <matthiasc@poet.de>
+
+ * gdk/tmpl/input_devices.sgml,
+ gdk/gdk-sections.txt, gdk/tmpl/windows.sgml: Updates.
+
2001-12-02 Matthias Clasen <matthiasc@poet.de>
* gdk/tmpl/dnd.sgml: Updates.
gdk_image_destroy
gdk_image_get_colormap
gdk_image_set_colormap
+
<SUBSECTION>
gdk_image_put_pixel
gdk_image_get_pixel
<TITLE>Drawing Primitives</TITLE>
<FILE>drawing</FILE>
GdkDrawable
-GdkDrawableClass
gdk_drawable_ref
gdk_drawable_unref
gdk_drawable_set_data
GDK_IS_DRAWABLE_CLASS
<SUBSECTION Private>
+GdkDrawableClass
gdk_draw_bitmap
</SECTION>
<TITLE>Graphics Contexts</TITLE>
<FILE>gcs</FILE>
GdkGC
-GdkGCClass
GdkGCValues
GdkGCValuesMask
GDK_GC
GDK_TYPE_GC
GDK_IS_GC
-gdk_gc_get_type
GDK_GC_CLASS
GDK_GC_GET_CLASS
GDK_IS_GC_CLASS
GDK_TYPE_JOIN_STYLE
GDK_TYPE_LINE_STYLE
GDK_TYPE_SUBWINDOW_MODE
+
+<SUBSECTION Private>
+GdkGCClass
+gdk_gc_get_type
</SECTION>
<SECTION>
GDK_TYPE_VISUAL
GDK_IS_VISUAL
GDK_IS_VISUAL_CLASS
-GdkVisualClass
GDK_VISUAL
GDK_VISUAL_CLASS
GDK_VISUAL_GET_CLASS
<SUBSECTION Private>
+GdkVisualClass
gdk_visual_get_type
</SECTION>
<SUBSECTION Standard>
GDK_TYPE_OVERLAP_TYPE
GDK_TYPE_RECTANGLE
+
+<SUBSECTION Private>
gdk_rectangle_get_type
</SECTION>
<TITLE>Keyboard Handling</TITLE>
<FILE>keys</FILE>
GdkKeymap
-GdkKeymapClass
GdkKeymapKey
GdkKeyInfo
gdk_keymap_get_default
<SUBSECTION>
gdk_keyval_to_unicode
gdk_unicode_to_keyval
+
<SUBSECTION Standard>
GDK_KEYMAP
GDK_IS_KEYMAP
GDK_TYPE_KEYMAP
-gdk_keymap_get_type
GDK_KEYMAP_CLASS
GDK_IS_KEYMAP_CLASS
GDK_KEYMAP_GET_CLASS
+
+<SUBSECTION Private>
+GdkKeymapClass
+gdk_keymap_get_type
</SECTION>
<SECTION>
<TITLE>Input Devices</TITLE>
<FILE>input_devices</FILE>
GdkDevice
-GdkDeviceClass
GdkInputSource
GdkInputMode
GdkDeviceKey
GDK_IS_DEVICE
GDK_IS_DEVICE_CLASS
GDK_TYPE_DEVICE
-gdk_device_get_type
<SUBSECTION Private>
+GdkDeviceClass
+gdk_device_get_type
GDK_MAX_TIMECOORD_AXES
</SECTION>
<SUBSECTION Standard>
GDK_TYPE_CURSOR_TYPE
GDK_TYPE_CURSOR
+
+<SUBSECTION Private>
gdk_cursor_get_type
</SECTION>
<para>
The #GdkColor structure is used to describe an
allocated or unallocated color.
-
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry><structfield>pixel</structfield></entry>
-<entry>For allocated colors, the value used to
-draw this color on the screen.</entry>
-</row>
-
-<row>
-<entry><structfield>red</structfield></entry>
-<entry>The red component of the color. This is
-a value between 0 and 65535, with 65535 indicating
-full intensitiy.</entry>
-</row>
-
-<row>
-<entry><structfield>green</structfield></entry>
-<entry>the blue component of the color.</entry>
-</row>
-
-<row>
-<entry><structfield>blue</structfield></entry>
-<entry>the green component of the color..</entry>
-</row>
-
-</tbody></tgroup></informaltable>
</para>
-@pixel:
-@red:
-@green:
-@blue:
+@pixel: For allocated colors, the value used to
+ draw this color on the screen.
+@red: The red component of the color. This is
+ a value between 0 and 65535, with 65535 indicating
+ full intensitiy.
+@green: The blue component of the color.
+@blue: The green component of the color.
+
<!-- ##### STRUCT GdkColormap ##### -->
<para>
-The colormap structure contains the following public
-fields.
-
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry><structfield>size</structfield></entry>
-<entry>For pseudo-color colormaps, the number of colors
-in the colormap..</entry>
-</row>
-
-<row>
-<entry><structfield>colors</structfield></entry>
-<entry>An array containing the current values in the
-colormap. This can be used to map from pixel values
-back to RGB values. This is only meaningful for
-pseudo-color colormaps.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
+The colormap structure contains the following public fields.
</para>
@parent_instance:
-@size:
-@colors:
+@size: For pseudo-color colormaps, the number of colors
+ in the colormap.
+@colors: An array containing the current values in the
+ colormap. This can be used to map from pixel values
+ back to RGB values. This is only meaningful for
+ pseudo-color colormaps.
+
<!-- ##### FUNCTION gdk_colormap_new ##### -->
<para>
-Create a new colormap for the given visual.
+Creates a new colormap for the given visual.
</para>
@visual: a #GdkVisual.
<!-- ##### FUNCTION gdk_colormap_change ##### -->
<para>
-Change the value of the first @ncolors in a private colormap
+Changes the value of the first @ncolors in a private colormap
to match the values in the <structfield>colors</structfield>
array in the color map. This function is obsolete and
should not be used. See gdk_color_change().
<!-- ##### FUNCTION gdk_colormap_alloc_color ##### -->
<para>
-Allocate a single color from a colormap.
+Allocates a single color from a colormap.
</para>
@colormap: a #GdkColormap.
<!-- ##### FUNCTION gdk_colormap_free_colors ##### -->
<para>
-Free previously allocated colors.
+Frees previously allocated colors.
</para>
@colormap: a #GdkColormap.
<!-- ##### FUNCTION gdk_colormap_get_visual ##### -->
<para>
-Return the visual for which a given colormap was created.
+Returns the visual for which a given colormap was created.
</para>
@colormap: a #GdkColormap.
<!-- ##### FUNCTION gdk_colors_store ##### -->
<para>
-Change the value of the first @ncolors colors in
+Changes the value of the first @ncolors colors in
a private colormap. This function is obsolete and
should not be used. See gdk_color_change().
</para>
<!-- ##### FUNCTION gdk_color_copy ##### -->
<para>
-Make a copy of a color structure. The result
+Makes a copy of a color structure. The result
must be freed using gdk_color_free().
</para>
<!-- ##### FUNCTION gdk_color_free ##### -->
<para>
-Free a color structure created with
+Frees a color structure created with
gdk_color_copy().
</para>
<!-- ##### FUNCTION gdk_colors_alloc ##### -->
<para>
-Allocate colors from a colormap. This function
+Allocates colors from a colormap. This function
is obsolete. See gdk_colormap_alloc_colors().
For full documentation of the fields, see
-the Xlib documentation for XAllocColorCells.
+the Xlib documentation for <function>XAllocColorCells()</function>.
</para>
@colormap: a #GdkColormap.
<!-- ##### FUNCTION gdk_colors_free ##### -->
<para>
-Free colors allocated with gdk_colors_alloc(). This
+Frees colors allocated with gdk_colors_alloc(). This
function is obsolete. See gdk_colormap_free_colors().
</para>
<!-- ##### FUNCTION gdk_color_white ##### -->
<para>
-Return the white color for a given colormap. The resulting
+Returns the white color for a given colormap. The resulting
value has already allocated been allocated.
</para>
<!-- ##### FUNCTION gdk_color_black ##### -->
<para>
-Return the black color for a given colormap. The resulting
+Returns the black color for a given colormap. The resulting
value has already benn allocated.
</para>
<!-- ##### FUNCTION gdk_color_parse ##### -->
<para>
-Parse a textual specification of a color and fill in
+Parses a textual specification of a color and fill in
the <structfield>red</structfield>,
<structfield>green</structfield>, and
<structfield>blue</structfield> fields of a
<!-- ##### FUNCTION gdk_color_alloc ##### -->
<para>
-Allocate a single color from a colormap.
+Allocates a single color from a colormap.
This function is obsolete. See gdk_colormap_alloc_color().
</para>
<!-- ##### FUNCTION gdk_color_change ##### -->
<para>
-Change the value of a color that has already
+Changes the value of a color that has already
been allocated. If @colormap is not a private
colormap, then the color must have been allocated
using gdk_colormap_alloc_colors() with the
<!-- ##### FUNCTION gdk_color_equal ##### -->
<para>
-Compare two colors.
+Compares two colors.
</para>
@colora: a #GdkColor.
@colora: a #GdkColor.
@Returns: The hash function appled to @colora
-<!-- # Unused Parameters # -->
-@colorb: NOT USED.
<para>
See the X Session Management Library documentation for more information on
session management and the Inter-Client Communication Conventions Manual
-(ICCCM) for information on the <literal>WM_CLIENT_LEADER property</literal>. (Both documents are
-part of the X Windows distribution.)
+(ICCCM) for information on the <literal>WM_CLIENT_LEADER</literal> property.
+(Both documents are part of the X Windows distribution.)
</para>
@sm_client_id: the client id assigned by the session manager when the
One additional field in each event is the
<structfield>source</structfield> field, which contains an
enumeration value describing the type of device; this currently
-can be one of
-%GDK_SOURCE_MOUSE,
- %GDK_SOURCE_PEN,
-%GDK_SOURCE_ERASER,
+can be one of %GDK_SOURCE_MOUSE, %GDK_SOURCE_PEN, %GDK_SOURCE_ERASER,
or %GDK_SOURCE_CURSOR. This field is present to allow simple
applications to (for instance) delete when they detect eraser
devices without having to keep track of complicated per-device
<para>
The interfaces in this section will most likely be considerably
modified in the future to accomodate devices that may have different
-sets of additional valuators than the pressure xtilt and ytilt.
+sets of additional valuators than the pressure <structfield>xtilt</structfield>
+and <structfield>ytilt</structfield>.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GdkDevice ##### -->
<para>
-
+A <structname>GdkDevice</structname> structure contains
+a detailed description of an extended input device. All
+fields are read-only; but you can use gdk_device_set_source(),
+gdk_device_set_mode(), gdk_device_set_key() and gdk_device_set_axis_use()
+to configure various aspects of the device.
</para>
@parent_instance:
-@name:
-@source:
-@mode:
-@has_cursor:
-@num_axes:
-@axes:
-@num_keys:
-@keys:
+@name: the name of this device.
+@source: the type of this device.
+@mode: the mode of this device
+@has_cursor: %TRUE if the pointer follows device motion.
+@num_axes: the length of the @axes array.
+@axes: an array of #GdkDeviceAxis, describing the axes of this device.
+@num_keys: the length of the @keys array.
+@keys: an array of #GdkDeviceKey, describing the mapped macro buttons
+ of this device.
<!-- ##### STRUCT GdkDeviceClass ##### -->
<para>
<!-- ##### STRUCT GdkDeviceKey ##### -->
<para>
-The #GdkDeviceKey structure contains information
-about the mapping of one device macro button onto
-a normal X key event. It has the following fields:
+The <structname>GdkDeviceKey</structname> structure contains information
+about the mapping of one device macro button onto a normal X key event.
+It has the following fields:
</para>
@keyval: the keyval to generate when the macro button is pressed.
<!-- ##### STRUCT GdkDeviceAxis ##### -->
<para>
-
+The <structname>GdkDeviceAxis</structname> structure contains information
+about the range and mapping of a device axis.
</para>
-@use:
-@min:
-@max:
+@use: specifies how the axis is used.
+@min: the minimal value that will be reported by this axis.
+@max: the maximal value that will be reported by this axis.
<!-- ##### ENUM GdkAxisUse ##### -->
<para>
<!-- ##### FUNCTION gdk_device_get_history ##### -->
<para>
-
+Obtains the motion history for a device.
</para>
-@device:
-@window:
-@start:
-@stop:
-@events:
-@n_events:
-@Returns:
+@device: a #GdkDevice.
+@window: the window wrt. which the event coordinates will be translated.
+@start: only return events newer than this timestamp.
+@stop: only return events older than this timestamp.
+@events: location to return a newly-allocated array of #GdkTimeCoord.
+@n_events: location to return the length of @events.
+@Returns: %TRUE if the @events were successfully filled.
<!-- ##### FUNCTION gdk_device_free_history ##### -->
</para>
@time: The timestamp for this event.
-@axes:
+@axes: the values of the device's axes.
<!-- ##### FUNCTION gdk_device_get_axis ##### -->
<para>
They appear in the <structfield>keyval</structfield> field of the
#GdkEventKey structure, which is passed to signal handlers for the
"key-press-event" and "key-release-event" signals.
-The complete list of key values can be found in the <gdk/gdkkeysyms.h>
-header file. <gdk/gdkkeysyms.h> is not included in <gtk/gtk.h>,
+The complete list of key values can be found in the <filename><gdk/gdkkeysyms.h></filename>
+header file. <filename><gdk/gdkkeysyms.h></filename> is not included in <filename><gtk/gtk.h></filename>,
it must be included independently, because the file is quite large.
</para>
<para>
<!-- ##### STRUCT GdkKeymap ##### -->
<para>
-
+A <structname>GdkKeymap</structname> defines the translation from keyboard state
+(including a hardware key, a modifier mask, and active keyboard group)
+to a keyval. This translation has two phases. The first phase is
+to determine the effective keyboard group and level for the keyboard
+state; the second phase is to look up the keycode/group/level triplet
+in the keymap and see what keyval it corresponds to.
</para>
@parent_instance:
<!-- ##### STRUCT GdkKeymapKey ##### -->
<para>
-
+A <structname>GdkKeymapKey</structname> is a hardware key that can
+be mapped to a keyval.
</para>
-@keycode:
-@group:
-@level:
+@keycode: the hardware keycode. This is an identifying number for a
+ physical key.
+@group: indicates movement in a horizontal direction. Usually groups are used
+ for two different languages. In group 0, a key might have two English
+ characters, and in group 1 it might have two Hebrew characters. The Hebrew
+ characters will be printed on the key next to the English characters.
+@level: indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key with the number "1" on it also has the
+ exclamation point ("!") character on it. The level indicates whether to use
+ the "1" or the "!" symbol. The letter keys are considered to have a lowercase
+ letter at level 0, and an uppercase letter at level 1, though only the
+ uppercase letter is printed.
<!-- ##### STRUCT GdkKeyInfo ##### -->
<para>
<!-- ##### FUNCTION gdk_keyval_name ##### -->
<para>
Converts a key value into a symbolic name.
-The names are the same as those in the <gdk/gdkkeysyms.h> header file
+The names are the same as those in the <filename><gdk/gdkkeysyms.h></filename> header file
but without the leading "GDK_".
</para>
@keyval: a key value.
-@Returns: a string containing the name of the key, or NULL if @keyval is not
+@Returns: a string containing the name of the key, or %NULL if @keyval is not
a valid key. The string should not be modified.
<!-- ##### FUNCTION gdk_keyval_is_upper ##### -->
<para>
-Returns TRUE if the given key value is in upper case.
+Returns %TRUE if the given key value is in upper case.
</para>
@keyval: a key value.
-@Returns: TRUE if @keyval is in upper case, or if @keyval is not subject to
+@Returns: %TRUE if @keyval is in upper case, or if @keyval is not subject to
case conversion.
<!-- ##### FUNCTION gdk_keyval_is_lower ##### -->
<para>
-Returns TRUE if the given key value is in lower case.
+Returns %TRUE if the given key value is in lower case.
</para>
@keyval: a key value.
-@Returns: TRUE if @keyval is in lower case, or if @keyval is not subject to
+@Returns: %TRUE if @keyval is in lower case, or if @keyval is not subject to
case conversion.
<!-- ##### MACRO GDK_PARENT_RELATIVE ##### -->
<para>
-
+A special value for <literal>GdkPixmap*</literal> variables, indicating
+that the background pixmap for a window should be inherited from the parent
+window.
</para>
-
<!-- ##### FUNCTION gdk_window_set_cursor ##### -->
<para>
projects / gtk4.git / commitdiff